home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / AppleGuide.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  13.4 KB  |  521 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        AppleGuide.h
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    ©1994-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __APPLEGUIDE__
  18. #define __APPLEGUIDE__
  19.  
  20. #ifndef __TYPES__
  21. #include <Types.h>
  22. #endif
  23. #ifndef __APPLEEVENTS__
  24. #include <AppleEvents.h>
  25. #endif
  26. #ifndef __FILES__
  27. #include <Files.h>
  28. #endif
  29.  
  30.  
  31.  
  32.  
  33. #if PRAGMA_ONCE
  34. #pragma once
  35. #endif
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. #if PRAGMA_IMPORT
  42. #pragma import on
  43. #endif
  44.  
  45. #if PRAGMA_STRUCT_ALIGN
  46.     #pragma options align=mac68k
  47. #elif PRAGMA_STRUCT_PACKPUSH
  48.     #pragma pack(push, 2)
  49. #elif PRAGMA_STRUCT_PACK
  50.     #pragma pack(2)
  51. #endif
  52.  
  53. /* Types*/
  54. typedef UInt32                             AGRefNum;
  55. typedef UInt32                             AGCoachRefNum;
  56. typedef UInt32                             AGContextRefNum;
  57.  
  58. struct AGAppInfo {
  59.     AEEventID                         eventId;
  60.     long                             refCon;
  61.     void *                            contextObj;                    /* private system field*/
  62. };
  63. typedef struct AGAppInfo                AGAppInfo;
  64. typedef AGAppInfo *                        AGAppInfoPtr;
  65. typedef AGAppInfoPtr *                    AGAppInfoHdl;
  66. typedef CALLBACK_API( OSErr , CoachReplyProcPtr )(Rect *pRect, Ptr name, long refCon);
  67. typedef CALLBACK_API( OSErr , ContextReplyProcPtr )(Ptr pInputData, Size inputDataSize, Ptr *ppOutputData, Size *pOutputDataSize, AGAppInfoHdl hAppInfo);
  68. typedef STACK_UPP_TYPE(CoachReplyProcPtr)                         CoachReplyUPP;
  69. typedef STACK_UPP_TYPE(ContextReplyProcPtr)                     ContextReplyUPP;
  70. enum { uppCoachReplyProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  71. enum { uppContextReplyProcInfo = 0x0000FFE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  72. #define NewCoachReplyProc(userRoutine)                             (CoachReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppCoachReplyProcInfo, GetCurrentArchitecture())
  73. #define NewContextReplyProc(userRoutine)                         (ContextReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppContextReplyProcInfo, GetCurrentArchitecture())
  74. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)     CALL_THREE_PARAMETER_UPP((userRoutine), uppCoachReplyProcInfo, (pRect), (name), (refCon))
  75. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo)  CALL_FIVE_PARAMETER_UPP((userRoutine), uppContextReplyProcInfo, (pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  76. /* Constants*/
  77.  
  78.  
  79.  
  80. enum {
  81.     kAGDefault                    = 0,
  82.     kAGFrontDatabase            = 1,
  83.     kAGNoMixin                    = (-1)
  84. };
  85.  
  86.  
  87.  
  88. enum {
  89.     kAGViewFullHowdy            = 1,                            /* Full-size Howdy*/
  90.     kAGViewTopicAreas            = 2,                            /* Full-size Topic Areas*/
  91.     kAGViewIndex                = 3,                            /* Full-size Index Terms*/
  92.     kAGViewLookFor                = 4,                            /* Full-size Look-For (Search)*/
  93.     kAGViewSingleHowdy            = 5,                            /* Single-list-size Howdy*/
  94.     kAGViewSingleTopics            = 6                                /* Single-list-size Topics*/
  95. };
  96.  
  97.  
  98.  
  99. enum {
  100.     kAGFileMain                    = FOUR_CHAR_CODE('poco'),
  101.     kAGFileMixin                = FOUR_CHAR_CODE('mixn')
  102. };
  103.  
  104. /* To test against AGGetAvailableDBTypes*/
  105.  
  106. enum {
  107.     kAGDBTypeBitAny                = 0x00000001,
  108.     kAGDBTypeBitHelp            = 0x00000002,
  109.     kAGDBTypeBitTutorial        = 0x00000004,
  110.     kAGDBTypeBitShortcuts        = 0x00000008,
  111.     kAGDBTypeBitAbout            = 0x00000010,
  112.     kAGDBTypeBitOther            = 0x00000080
  113. };
  114.  
  115.  
  116.  
  117. typedef UInt16                             AGStatus;
  118. /* Returned by AGGetStatus*/
  119.  
  120. enum {
  121.     kAGIsNotRunning                = 0,
  122.     kAGIsSleeping                = 1,
  123.     kAGIsActive                    = 2
  124. };
  125.  
  126. /* Flags used in AGOpen, AGOpenWithSearch, AGOpenWithView*/
  127.  
  128. enum {
  129.     kHelpViewerSearchAll        = (1 << 0)
  130. };
  131.  
  132. typedef UInt16                             AGWindowKind;
  133. /* Returned by AGGetFrontWindowKind*/
  134.  
  135. enum {
  136.     kAGNoWindow                    = 0,
  137.     kAGAccessWindow                = 1,
  138.     kAGPresentationWindow        = 2
  139. };
  140.  
  141. /* Error Codes*/
  142.  
  143. /* Not an enum, because other OSErrs are valid.*/
  144. typedef SInt16                             AGErr;
  145. /* Apple Guide error codes*/
  146.  
  147. enum {
  148.                                                                 /* -------------------- Apple event reply codes*/
  149.     kAGErrUnknownEvent            = -2900,
  150.     kAGErrCantStartup            = -2901,
  151.     kAGErrNoAccWin                = -2902,
  152.     kAGErrNoPreWin                = -2903,
  153.     kAGErrNoSequence            = -2904,
  154.     kAGErrNotOopsSequence        = -2905,
  155.     kAGErrReserved06            = -2906,
  156.     kAGErrNoPanel                = -2907,
  157.     kAGErrContentNotFound        = -2908,
  158.     kAGErrMissingString            = -2909,
  159.     kAGErrInfoNotAvail            = -2910,
  160.     kAGErrEventNotAvailable        = -2911,
  161.     kAGErrCannotMakeCoach        = -2912,
  162.     kAGErrSessionIDsNotMatch    = -2913,
  163.     kAGErrMissingDatabaseSpec    = -2914,
  164.     kAGMissingSequenceMap        = -2915,                        /* -------------------- Coach's Chalkboard reply codes*/
  165.     kAGErrItemNotFound            = -2925,
  166.     kAGErrBalloonResourceNotFound = -2926,
  167.     kAGErrChalkResourceNotFound    = -2927,
  168.     kAGErrChdvResourceNotFound    = -2928,
  169.     kAGErrAlreadyShowing        = -2929,
  170.     kAGErrBalloonResourceSkip    = -2930,
  171.     kAGErrItemNotVisible        = -2931,
  172.     kAGErrReserved32            = -2932,
  173.     kAGErrNotFrontProcess        = -2933,
  174.     kAGErrMacroResourceNotFound    = -2934,                        /* -------------------- API reply codes*/
  175.     kAGErrAppleGuideNotAvailable = -2951,
  176.     kAGErrCannotInitCoach        = -2952,
  177.     kAGErrCannotInitContext        = -2953,
  178.     kAGErrCannotOpenAliasFile    = -2954,
  179.     kAGErrNoAliasResource        = -2955,
  180.     kAGErrDatabaseNotAvailable    = -2956,
  181.     kAGErrDatabaseNotOpen        = -2957,
  182.     kAGErrMissingAppInfoHdl        = -2958,
  183.     kAGErrMissingContextObject    = -2959,
  184.     kAGErrInvalidRefNum            = -2960,
  185.     kAGErrDatabaseOpen            = -2961,
  186.     kAGErrInsufficientMemory    = -2962
  187. };
  188.  
  189. /* Events*/
  190.  
  191. /* Not an enum because we want to make assignments.*/
  192. typedef UInt32                             AGEvent;
  193. /* Handy events for AGGeneral.*/
  194.  
  195. enum {
  196.                                                                 /* Panel actions (Require a presentation window).*/
  197.     kAGEventDoCoach                = FOUR_CHAR_CODE('doco'),
  198.     kAGEventDoHuh                = FOUR_CHAR_CODE('dhuh'),
  199.     kAGEventGoNext                = FOUR_CHAR_CODE('gonp'),
  200.     kAGEventGoPrev                = FOUR_CHAR_CODE('gopp'),
  201.     kAGEventHidePanel            = FOUR_CHAR_CODE('pahi'),
  202.     kAGEventReturnBack            = FOUR_CHAR_CODE('gobk'),
  203.     kAGEventShowPanel            = FOUR_CHAR_CODE('pash'),
  204.     kAGEventTogglePanel            = FOUR_CHAR_CODE('patg')
  205. };
  206.  
  207. /* Functions*/
  208.  
  209. /*
  210.    AGClose
  211.    Close the database associated with the AGRefNum.
  212. */
  213.  
  214. EXTERN_API( AGErr )
  215. AGClose                            (AGRefNum *                refNum)                                TWOWORDINLINE(0x7011, 0xAA6E);
  216.  
  217. /*
  218.    AGGeneral
  219.    Cause various events to happen.
  220. */
  221.  
  222. EXTERN_API( AGErr )
  223. AGGeneral                        (AGRefNum                 refNum,
  224.                                  AGEvent                 theEvent)                            TWOWORDINLINE(0x700D, 0xAA6E);
  225.  
  226. /*
  227.    AGGetAvailableDBTypes
  228.    Return the database types available for this application.
  229. */
  230.  
  231. EXTERN_API( UInt32 )
  232. AGGetAvailableDBTypes            (void)                                                        TWOWORDINLINE(0x7008, 0xAA6E);
  233.  
  234. /*
  235.    AGGetFrontWindowKind
  236.    Return the kind of the front window.
  237. */
  238.  
  239. EXTERN_API( AGWindowKind )
  240. AGGetFrontWindowKind            (AGRefNum                 refNum)                                TWOWORDINLINE(0x700C, 0xAA6E);
  241.  
  242. /*
  243.    AGGetFSSpec
  244.    Return the FSSpec for the AGRefNum.
  245. */
  246.  
  247. EXTERN_API( AGErr )
  248. AGGetFSSpec                        (AGRefNum                 refNum,
  249.                                  FSSpec *                fileSpec)                            TWOWORDINLINE(0x700F, 0xAA6E);
  250.  
  251. /*
  252.    AGGetStatus
  253.    Return the status of Apple Guide.
  254. */
  255.  
  256. EXTERN_API( AGStatus )
  257. AGGetStatus                        (void)                                                        TWOWORDINLINE(0x7009, 0xAA6E);
  258.  
  259. /*
  260.    AGInstallCoachHandler
  261.    Install a Coach object location query handler.
  262. */
  263.  
  264. EXTERN_API( AGErr )
  265. AGInstallCoachHandler            (CoachReplyUPP             coachReplyProc,
  266.                                  long                     refCon,
  267.                                  AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7012, 0xAA6E);
  268.  
  269. /*
  270.    AGInstallContextHandler
  271.    Install a context check query handler.
  272. */
  273.  
  274. EXTERN_API( AGErr )
  275. AGInstallContextHandler            (ContextReplyUPP         contextReplyProc,
  276.                                  AEEventID                 eventID,
  277.                                  long                     refCon,
  278.                                  AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7013, 0xAA6E);
  279.  
  280. /*
  281.    AGIsDatabaseOpen
  282.    Return true if the database associated with the AGRefNum is open.
  283. */
  284.  
  285. EXTERN_API( Boolean )
  286. AGIsDatabaseOpen                (AGRefNum                 refNum)                                TWOWORDINLINE(0x7006, 0xAA6E);
  287.  
  288. /*
  289.    AGOpen
  290.    Open a guide database.
  291. */
  292.  
  293. EXTERN_API( AGErr )
  294. AGOpen                            (ConstFSSpecPtr         fileSpec,
  295.                                  UInt32                 flags,
  296.                                  Handle                 mixinControl,
  297.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7001, 0xAA6E);
  298.  
  299. /*
  300.    AGOpenWithSearch
  301.    Open a guide database and preset a search string.
  302. */
  303.  
  304. EXTERN_API( AGErr )
  305. AGOpenWithSearch                (ConstFSSpecPtr         fileSpec,
  306.                                  UInt32                 flags,
  307.                                  Handle                 mixinControl,
  308.                                  ConstStr255Param         searchString,
  309.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7002, 0xAA6E);
  310.  
  311. /*
  312.    AGOpenWithSequence
  313.    Open a guide database and display a presentation window sequence.
  314. */
  315.  
  316. EXTERN_API( AGErr )
  317. AGOpenWithSequence                (ConstFSSpecPtr         fileSpec,
  318.                                  UInt32                 flags,
  319.                                  Handle                 mixinControl,
  320.                                  short                     sequenceID,
  321.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7004, 0xAA6E);
  322.  
  323. /*
  324.    AGOpenWithView
  325.    Open a guide database and override the default view.
  326. */
  327.  
  328. EXTERN_API( AGErr )
  329. AGOpenWithView                    (ConstFSSpecPtr         fileSpec,
  330.                                  UInt32                 flags,
  331.                                  Handle                 mixinControl,
  332.                                  short                     viewNum,
  333.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7005, 0xAA6E);
  334.  
  335. /*
  336.    AGQuit
  337.    Make Apple Guide quit.
  338. */
  339.  
  340. EXTERN_API( AGErr )
  341. AGQuit                            (void)                                                        TWOWORDINLINE(0x7010, 0xAA6E);
  342.  
  343. /*
  344.    AGRemoveCoachHandler
  345.    Remove the Coach object location query handler.
  346. */
  347.  
  348. EXTERN_API( AGErr )
  349. AGRemoveCoachHandler            (AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7014, 0xAA6E);
  350.  
  351. /*
  352.    AGRemoveContextHandler
  353.    Remove the context check query handler.
  354. */
  355.  
  356. EXTERN_API( AGErr )
  357. AGRemoveContextHandler            (AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7015, 0xAA6E);
  358.  
  359. /*
  360.    AGStart
  361.    Start up Apple Guide in the background.
  362. */
  363.  
  364. EXTERN_API( AGErr )
  365. AGStart                            (void)                                                        TWOWORDINLINE(0x700A, 0xAA6E);
  366.  
  367.  
  368.  
  369. /* typedef's*/
  370.  
  371. typedef FSSpec                             AGFileFSSpecType;
  372. typedef short                             AGFileSelectorCountType;
  373. typedef short                             AGFileSelectorIndexType;
  374. typedef OSType                             AGFileSelectorType;
  375. typedef long                             AGFileSelectorValueType;
  376. typedef short                             AGFileDBType;
  377. typedef Str63                             AGFileDBMenuNamePtr;
  378. typedef short                             AGFileDBScriptType;
  379. typedef short                             AGFileDBRegionType;
  380. typedef short                             AGFileMajorRevType;
  381. typedef short                             AGFileMinorRevType;
  382. typedef short                             AGFileCountType;
  383. /* Database types (for AGFileDBType parameter).*/
  384.  
  385. enum {
  386.     kAGFileDBTypeAny            = 0,
  387.     kAGFileDBTypeHelp            = 1,
  388.     kAGFileDBTypeTutorial        = 2,
  389.     kAGFileDBTypeShortcuts        = 3,
  390.     kAGFileDBTypeAbout            = 4,
  391.     kAGFileDBTypeOther            = 8
  392. };
  393.  
  394.  
  395.  
  396. EXTERN_API( OSErr )
  397. AGFileGetDBMenuName                (const FSSpec *            fileSpec,
  398.                                  Str63                     menuItemNameString);
  399.  
  400. /* Get the database type.*/
  401. EXTERN_API( OSErr )
  402. AGFileGetDBType                    (const FSSpec *            fileSpec,
  403.                                  AGFileDBType *            databaseType);
  404.  
  405. /*
  406.    Get the version of the software
  407.    that created this database.
  408. */
  409. EXTERN_API( OSErr )
  410. AGFileGetDBVersion                (const FSSpec *            fileSpec,
  411.                                  AGFileMajorRevType *    majorRev,
  412.                                  AGFileMinorRevType *    minorRev);
  413.  
  414. /* Get the database script and region information.*/
  415. EXTERN_API( OSErr )
  416. AGFileGetDBCountry                (const FSSpec *            fileSpec,
  417.                                  AGFileDBScriptType *    script,
  418.                                  AGFileDBRegionType *    region);
  419.  
  420. /* Return the number of selectors in database.*/
  421. EXTERN_API( AGFileSelectorCountType )
  422. AGFileGetSelectorCount            (const FSSpec *            fileSpec);
  423.  
  424. /*
  425.    Get the i-th database selector (1 to AGFileSelectorCountType)
  426.    and its value.
  427. */
  428. EXTERN_API( OSErr )
  429. AGFileGetSelector                (const FSSpec *            fileSpec,
  430.                                  AGFileSelectorIndexType  selectorNumber,
  431.                                  AGFileSelectorType *    selector,
  432.                                  AGFileSelectorValueType * value);
  433.  
  434. /* Return true if database is mixin.*/
  435. EXTERN_API( Boolean )
  436. AGFileIsMixin                    (const FSSpec *            fileSpec);
  437.  
  438. /*
  439.    Return the number of database files
  440.    of the specified databaseType and main/mixin.
  441.    Any file creator is acceptible,
  442.    but type must be kAGFileMain or kAGFileMixin.
  443. */
  444. EXTERN_API( AGFileCountType )
  445. AGFileGetDBCount                (short                     vRefNum,
  446.                                  long                     dirID,
  447.                                  AGFileDBType             databaseType,
  448.                                  Boolean                 wantMixin);
  449.  
  450. /*
  451.    Get the FSSpec for the dbIndex-th database
  452.    of the specified databaseType and main/mixin.
  453.    Any file creator is acceptible,
  454.    but type must be kAGFileMain or kAGFileMixin.
  455. */
  456. EXTERN_API( OSErr )
  457. AGFileGetIndDB                    (short                     vRefNum,
  458.                                  long                     dirID,
  459.                                  AGFileDBType             databaseType,
  460.                                  Boolean                 wantMixin,
  461.                                  short                     dbIndex,
  462.                                  FSSpec *                fileSpec);
  463.  
  464. /*
  465.    This selector must match with the application
  466.    creator in order for this file to appear in the 
  467.    application's Help menu. Ignored for mixin files
  468.    because they never appear in the Help menu anyway.
  469.    If empty (zeros), will appear in the Help menu
  470.    of any host application.
  471. */
  472. EXTERN_API( OSErr )
  473. AGFileGetHelpMenuAppCreator        (const FSSpec *            fileSpec,
  474.                                  OSType *                helpMenuAppCreator);
  475.  
  476. /*
  477.    This selector must match in the main and mixin
  478.    files in order for the mixin to mix-in with the main.
  479.    Empty (zeros) selectors are valid matches.
  480.    A '****' selector will mix-in with any main.
  481. */
  482. EXTERN_API( OSErr )
  483. AGFileGetMixinMatchSelector        (const FSSpec *            fileSpec,
  484.                                  OSType *                mixinMatchSelector);
  485.  
  486. /*
  487.    This is the text of the balloon for the
  488.    Help menu item for this database.
  489. */
  490. EXTERN_API( OSErr )
  491. AGFileGetHelpMenuBalloonText    (const FSSpec *            fileSpec,
  492.                                  Str255                 helpMenuBalloonString);
  493.  
  494.  
  495. EXTERN_API( OSErr )
  496. AGGetSystemDB                    (AGFileDBType             databaseType,
  497.                                  Boolean                 wantMixin,
  498.                                  FSSpec *                pFileSpec);
  499.  
  500.  
  501. #if PRAGMA_STRUCT_ALIGN
  502.     #pragma options align=reset
  503. #elif PRAGMA_STRUCT_PACKPUSH
  504.     #pragma pack(pop)
  505. #elif PRAGMA_STRUCT_PACK
  506.     #pragma pack()
  507. #endif
  508.  
  509. #ifdef PRAGMA_IMPORT_OFF
  510. #pragma import off
  511. #elif PRAGMA_IMPORT
  512. #pragma import reset
  513. #endif
  514.  
  515. #ifdef __cplusplus
  516. }
  517. #endif
  518.  
  519. #endif /* __APPLEGUIDE__ */
  520.  
  521.